[Разбор] Полный Разбор yt-dlp Web Downloader

Введение

Этот проект — веб-приложение для загрузки видео с YouTube и других поддерживаемых сайтов с помощью утилиты yt-dlp. На клиенте — удобная веб-панель, на сервере — FastAPI-приложение, которое запускает yt-dlp, передаёт логи и прогресс в реальном времени, управляет загрузками и отдаёт готовые файлы.

1. Клиентская часть: index.html

1.1 Структура

- Основной контейнер #main-container: тёмная панель с границей, отступами и тенями, ограничена по ширине 640px, центрирована с отступом сверху.

- Заголовок — <h2> с названием приложения.

- Форма #downloadForm с элементами:
- textarea для вставки ссылки видео.
- <input type="file"> для загрузки cookies (нужно для приватных видео или сайтов с авторизацией).
- input[type="text"] для ввода опций yt-dlp.
- Подсказки с примерами опций (показывает популярные параметры yt-dlp).
- Группа кнопок
- Начать загрузку
- Отмена
- Загрузить на ПК (появляется после завершения загрузки)
- Показать форматы

- Прогресс-бар с визуальным отображением прогресса загрузки и текстовым процентом.

- Вывод форматов (текстовое поле) при запросе доступных форматов для URL.

- Терминал — окно с лентой логов, куда выводятся стримы с сервера.

- История — список ранее скачанных файлов с копированием ссылок и очисткой.

- Навигация с полезными ссылками — для перехода к ресурсам yt-dlp, FFmpeg и другое.

1.2 Стили

1.3 Скрипты

- Управление историей:
- Хранит историю в localStorage до 50 записей.
- Позволяет копировать ссылки кнопками.
- Очистка удаляет и файлы на сервере.

- Обработка прогресса:
- Parses вывод yt-dlp по строчкам.
- Переопределяет строки с возвращаемым курсором \r для обновления прогресса.
- Обновляет прогресс-бар и текст с процентом.

- Асинхронная загрузка с отменой:
- Запускает POST запрос на /download_stream с FormData.
- Обрабатывает stream тела ответа, динамически обновляя интерфейс.
- Возможность отмены загрузки HTTP AbortController.

- Показ доступных форматов:
- Запрос к /formats?url=...
- Отображает полученный список форматов.

- Копирование ссылок и взаимодействия с буфером обмена.

2. Серверная часть: main.py

2.1 Архитектура проекта и директории

- templates/ — HTML-шаблоны.
- downloads/ — папка для временного хранения скачанных видео.
- static/ — (может быть) статика.
- Роуты реализованы на FastAPI.

2.2 Основные константы и пути

- YT_DLP_PATH — путь к бинарнику yt-dlp.
- OUTPUT_TEMPLATE — формат имени для выходных файлов (использует title и расширение).
- Директории получаются относительно текущего файла.

2.3 Утилиты

- sanitize_filename(name) — избавляется от подозрительных символов в имени файла, заменяя на _.
- filter_user_options(options) — убирает из пользовательских опций параметры вывода, чтобы избежать конфликтов.
- is_extract_audio(options) — проверяет, запрашивал ли пользователь просто аудио (флаги -x, --extract-audio).
 Экспериментальная нормализация URL:* В коде присутствует функция для базовой очистки ссылок, нацеленная на упрощение адресов перед передачей в основной обработчик

2.4 Формирование команды yt-dlp: build_cmd

2.5 Асинхронное управление yt-dlp: stream_yt_dlp

2.6 Эндпоинты

- GET / — отдаёт статическую страницу index.html.
- POST /download_stream — принимает URL, опции и файл cookies, запускает загрузку и выводит стримингом логи.
- GET /formats — возвращает список форматов для данного URL, вызывая yt-dlp с -F.
- POST /clear_history_files — очищает папку скачанных файлов.
- GET /download_file — отдает скачанный файл с проверкой безопасности имени и заголовками для скачивания.

2.7 Безопасность

3. Взаимодействие клиента и сервера

4. Пример использования

  1. Вставьте ссылку YouTube (например, https://www.youtube.com/watch?v=...).
  2. По желанию добавьте cookies для приватного доступа.
  3. Введите опции yt-dlp (качество, преобразование аудио и т. д.).
  4. Нажмите «Начать загрузку».
  5. Следите за прогрессом и логами.
  6. После завершения скачайте файл.
  7. Просматривайте историю, копируйте ссылки, очищайте её по нужде.

5. Обоснование архитектурных решений

- FastAPI и асинхронность — позволяет обрабатывать потоковые ответы эффективно, не блокируя сервер.
- yt-dlp через оболочку — использует мощный инструмент без переписывания логики загрузки.
- Стриминг логов — даёт лучший UX с обратной связью.
- LocalStorage для истории — простое решение без необходимости бэкенд базы.
- Стандартизированные пути и фильтры — минимизируют риски взлома и конфликтов.
- ARIA и доступность — поддержка пользователей с особыми потребностями.

6. Возможные расширения

7. Как пользоваться окном «Показать форматы» и формировать команду загрузки

7.1 Зачем нужна функция «Показать форматы»

Видео, размещённые на YouTube и других платформах, обычно доступны в разных качествах и форматах: например, 1080p mp4, 720p webm, аудио отдельно и т.д. yt-dlp позволяет выбрать конкретный формат для загрузки.

В интерфейсе кнопка «Показать форматы» запрашивает у yt-dlp список доступных форматов для указанного видео и отображает его во втором текстовом окне. Это помогает понять, какие варианты есть, и подобрать нужные опции.

7.2 Как использовать окно «Показать форматы»

  1. Вставьте ссылку на видео в поле «Вставьте ссылку сюда».
  2. Нажмите кнопку «Показать форматы».
  3. В появившемся блоке снизу вы увидите примерно такой список (пример):
format code  extension  resolution note
249          webm       audio only tiny   53k , opus @ 50k, 1.45MiB
250          webm       audio only tiny   68k , opus @ 70k, 1.81MiB
140          m4a        audio only tiny  129k , m4a_dash container, mp4a.40.2@128k, 3.54MiB
137          mp4        1080p            4479k , avc1.640028, 30fps, video only, 114.64MiB
136          mp4        720p             1856k , avc1.4d401f, 30fps, video only, 45.84MiB
135          mp4        480p             966k , avc1.4d401e, 30fps, video only, 24.75MiB
...

- format code - уникальный идентификатор формата, который нужно указать для загрузки.
- extension - расширение файла.
- resolution и note - описание качества и особенности.

7.3 Пример формирования команды для загрузки

По умолчанию в проекте используется такая команда для выбора форматов:

-S res:1080,vcodec:av1 (bv*[height<=1080]+ba) / res:1080,vcodec:vp9 (bv*[height<=1080]+ba) / bestvideo[ext=mp4][height<=1080]+bestaudio[ext=m4a] / best[ext=mp4] / best / bv*[height<=1080]+ba / b
--merge-output-format mp4

Эта сложная строка с -S (сортировкой форматов) пытается выбрать лучшее качество до 1080p, предпочтительно с кодеком av1 или vp9, с объединением аудио+видео в MP4.

7.4 Как подставить конкретные форматы из списка

Если вы получили список форматов и хотите загрузить, например, видео 1080p и аудио 128k, то можно указать:

-f 137+140

где

- 137 - видео в формате mp4 1080p,
- 140 - аудио в формате m4a 128k.

В поле «Дополнительные опции yt-dlp» напишите:

-f 137+140 --merge-output-format mp4

Это загрузит указанное видео и аудио и объединит их в MP4.

7.5 Пример полного сценария

  1. Вставьте ссылку.
  2. Нажмите «Показать форматы» и выберите нужные коды.
  3. В «Дополнительные опции» введите строку с -f или любыми другими параметрами.
  4. Нажмите «Начать загрузку».

7.6 Полезные параметры

Этот механизм позволяет гибко управлять загрузками, используя мощь yt-dlp через простой веб-интерфейс.

7.7 Шаблоны команд yt-dlp для поля «Дополнительные опции»

1. Скачать лучшее видео с объединением аудио (до 1080p, MP4)

-f 137+140 --merge-output-format mp4 --no-playlist

- -f 137+140 — видео 1080p (код 137) + аудио 128k (код 140)
- --merge-output-format mp4 — объединить аудио и видео в MP4
- --no-playlist — скачать только одно видео из плейлиста

2. Скачать видео в наилучшем качестве с объединением в MKV

-f bestvideo+bestaudio --merge-output-format mkv --no-playlist

- -f bestvideo+bestaudio — взять лучшие видео и аудиодорожки
- --merge-output-format mkv — объединить в контейнер MKV
- --no-playlist — без плейлистов

3. Скачать только аудио с конвертацией в MP3 с качеством 320 kbps

--extract-audio --audio-format mp3 --audio-quality 320 --no-playlist

- --extract-audio — извлечь аудио из видео
- --audio-format mp3 — конвертировать аудио в MP3
- --audio-quality 320 — установить битрейт 320 кбит/с
- --no-playlist — скачать только одно видео

4. Скачать аудио с максимальным качеством (без конкретного битрейта)

--extract-audio --audio-format mp3 --audio-quality 0 --no-playlist

- --audio-quality 0 — максимально возможное качество (оптимальное значение для MP3)

5. Скачать аудио без конвертации, в исходном формате

-f bestaudio --no-playlist --extract-audio

- -f bestaudio — выбрать лучшую аудиодорожку
- --extract-audio — извлечь аудио
- --no-playlist — без плейлистов

6. Скачать субтитры на русском и английском языках

--write-sub --sub-lang ru,en --skip-download

- --write-sub — скачать субтитры
- --sub-lang ru,en — языки субтитров
- --skip-download — не скачивать само видео

Как скачать определённый участок видео с точной обрезкой

Для загрузки только части видео (например, с 1-й по 2-ю минуту), при этом сохраняя обрезку максимально точно по ключевым кадрам, используйте опции:

--force-keyframes-at-cuts --download-sections "*00:01:00-00:02:00"

Эта команда скачает указанный промежуток без артефактов, делая резы именно там, где расположены ключевые кадры.

Пример полной команды:

yt-dlp --force-keyframes-at-cuts --download-sections "*00:01:00-00:02:00" <URL>

Если нужно скачать несколько секций подряд – указывай их через запятую:

--force-keyframes-at-cuts --download-sections "*00:01:00-00:02:00,*00:03:30-00:04:00"

Как пользоваться шаблонами

  1. Вставьте ссылку [[Полный Разбор yt-dlp Web Downloader]]на видео.
  2. Нажмите «Показать форматы» и выберите нужные коды форматов.
  3. Вставьте выбранный шаблон в поле «Дополнительные опции yt-dlp». При необходимости замените коды форматов из шага 2.
  4. Нажмите «Начать загрузку».

Заключение

Этот проект — отличный пример современного веб-сервиса с обращением к CLI-инструментам, потоковой обработкой и удобным интерфейсом. Он собирает надёжные компоненты, делая сложную задачу загрузки видео доступной для обычных пользователей.

← Назад